Skip to content

DEV-1047 NeuroLynQ host support: know the nRF52840 Span, and a NeuroLynQ-mode Verisense as a GQ - #308

Open
marknolan wants to merge 3 commits into
masterfrom
DEV-1047_neurolynq_host_support
Open

marknolan wants to merge 3 commits into
masterfrom
DEV-1047_neurolynq_host_support

Conversation

@marknolan

@marknolan marknolan commented Sep 28, 2026 •

Copy link
Copy Markdown
Member

Summary

This is DEV-1047's host-side change to the Java driver, as one PR. It replaces #302, #303 and #304, which were a stack. Each commit is one of those PRs, unchanged, and each old PR keeps its description and discussion.

Commit Was What it does Test
ef37c0a #302 Know the nRF52840 Span by Nordic's VID and its product string API_00012_SpanNrf52840IdentityTest
c446e1b #303 Tell a NeuroLynQ-mode Verisense from a stock one API_00013_VerisenseNeuroLynQMarkerTest
2c00a06 #304 Recognise a NeuroLynQ-mode Verisense as a GQ API_00014_VerisenseNeuroLynQVersionTest

Merge order

This PR goes first. The Shimmer-Advance-API PR, ShimmerResearch/Shimmer-Advance-API#483, builds against this repo's master in CI. The ConsensysApps PR, ShimmerResearch/ConsensysApps#494, follows that one.

Tests

The three classes above, 22 tests, pass (2026-09-28).

Bench

On 2026-09-28 this exact tree ran in the NeuroLynQ software, together with the other two PRs. The bench had an Ezurio BL654 USB Span and an SR9, with three GQs on a Base6. Discovery, the channel analysis, pairing and streaming all worked (DEV-1047).

Other host stacks

None need these changes. The C#, Python and Swift APIs have no Span or NeuroLynQ code, and neurolynq-web-sdk already knows the nRF52840 Span by its PID.

DEV-1061's #306 was stacked on #304's branch and can move onto this one.

🤖 Generated with Claude Code

marknolan and others added 3 commits September 24, 2026 17:31
The nRF52840 Span (verisense-firmware SR9_SPAN_NRF52840) is one CDC port
under Nordic's VID, with no FTDI bridge and no MSP430 BSL. Nothing in
SH_SEARCH describes it, and the only supported SPAN_VERSION assumes a BSL.

- SH_SEARCH.SPAN_NRF52840 ("NeuroLynQ Span") and
  SERIAL_PORT.NORDIC_VEND_ID ("1915"), with isSpanNrf52840() as the one
  rule every platform's detection applies. It takes no PID on purpose:
  0x5210 is provisional and unallocated under Nordic's VID, and a PID
  match would need a host release whenever it changes.
- SPAN_VERSION.SPAN_NRF52840, supported, and isMspBslSupported() so a
  caller can tell a Span reset and programmed through a BSL from one
  that is not. Appended, so the existing ordinals stand.

API_00012 pins the rule to the product strings Windows reported for the
bench devices on 2026-09-24, including the NeuroLynQ-mode Verisense on
the same VID, which is a node and must not match.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Both enumerate as 1915:520F. The NeuroLynQ firmware says which it is in
its USB product string instead (verisense-firmware #654): "-NeuroLynQ"
after the name prefix, whichever prefix the unit carries, as in
Verisense-NeuroLynQ-01-2511210195BC. DEV-1047 settled on that string as
the only signal, with no PID change.

SH_SEARCH.VERISENSE_NEUROLYNQ and isVerisenseNeuroLynQ() are that rule.
The two kinds need different drivers: a NeuroLynQ-mode Verisense serves
the ShimmerGQ $ dock protocol, and not its native one.

API_00013 covers the bench node's string, the unprovisioned and
provisioned-prefix forms, a stock unit, and the nRF52840 Span, which says
NeuroLynQ too but is not a node.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Docked, a Verisense in NeuroLynQ mode answers VER with its own hardware
ID (61 to 68) and the GQ's firmware ID, GQ_802154. It answers and streams
as a GQ does, but the host decided GQ-ness by hardware ID alone. So the
bench node (hardware 68, v2.1.1) stayed an unrecognised device with
"Unknown" firmware, and NeuroLynQ could not offer it for pairing.

ShimmerVerObject
- isVerisenseNeuroLynQ(): Verisense hardware running GQ_802154, the one
  firmware ID that identifies it.
- isShimmerGenGq() includes it. Every caller, some 60 across the stack,
  uses the no-argument form, so this is the one place that decides.
- isShimmerGenVerisense() excludes it. It sends GQ data, already scaled
  to the GQ's ADC, so SensorGSR must take the GQ's ADC properties rather
  than a Verisense's.
- isSupportedConfigViaUart() and isSupportedRtcConfigViaUart() include
  it, so a dock reads and writes its InfoMem image and clock as it does a
  GQ's. The node implements both commands.
- isSupportedSdCardAccess(), keyed on the GQ's firmware ID, excludes it:
  it has no SD card, and its USB has no mass storage.
- Its firmware label follows, as "GQ_802154".

Configuration: the GQ sensor compatibility lists match GQs by hardware,
so each gains an entry matching GQ_802154 on any hardware. Only a
NeuroLynQ-mode Verisense needs it.

A stock Verisense, firmware VERISENSE, is unchanged. API_00014 covers
it, a GQ, and every Verisense hardware ID.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

@jyong15 jyong15 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adversarial review: Shimmer-Java-Android-API #308 (DEV-1047 driver roll-up)

Verdict: mergeable with fixes. CI is green and the branch merges cleanly with current master (merged tree builds, 199/199 tests). The most serious problem is stack-level: Span and node detection is Windows-only, and the node gets firmware version code -1.

One of six coordinated reviews of the DEV-1047 / DEV-1061 stack (#308, #306; ShimmerResearch/Shimmer-Advance-API#483, #482; ShimmerResearch/ConsensysApps#494, #493), with builds and tests run locally against the sibling branches.

Findings

Verified: ShimmerDriver 125/125 (the 22 new tests included), ShimmerDriverPC build OK, GitHub CI green. Merge with master clean (only ShimmerVerObject.java on both sides); merged tree 199/199. A compiled probe confirmed F1, F4 and F5.

  • F1 Minor, confirmed. ShimmerVerObject.java:287: the node gets mFirmwareVersionCode = -1 while a GQ gets 6, because the ladder keys on GQ hardware IDs and isVerisenseNeuroLynQ() was added only to the label condition (:250). #306's description says "a node takes firmware version code 6"; it does not. Any >= 6 check (timestamp width in ShimmerObject and ShimmerBluetooth) is false for a node.
  • F2 Minor. Other hardware-keyed lists still exclude the node: ExpansionBoardDetails.LIST_OF_UNITS_WITH_EXP_BRDS (:32), getMapOfByteDescriptions (:119), isSupportedSdDataImport(int); and the static isShimmerGenVerisense(int) disagrees with the instance method for the same device.
  • F3 Major at stack level. Windows-only detection (cross-stack item 7). HwDriverShimmerDeviceDetails.java:352 javadoc is false.
  • F4 Minor. HwDriverShimmerDeviceDetails.java:357-360: Span match is a case-insensitive substring with no PID check, so "NeuroLynQ Span 2" or any future variant is claimed as the nRF52840 Span. toUpperCase() without a Locale.
  • F5 Minor. The node marker constant (:184-186) is "-NeuroLynQ-" with a trailing hyphen; the firmware and neurolynq-web define "-NeuroLynQ". A truncated product string classifies a node as stock. isVerisenseNeuroLynQ(String) takes no VID, unlike the Span rule. verisense-firmware was not available to confirm.
  • F6 Minor. A null or empty product string yields "stock Verisense"; VerisenseUsbManager.isStockVerisense passes null when the composite device is missing, so a node whose descriptor read failed is opened with the native Verisense protocol.
  • F7 Minor. Hardware list 61, 62, 63, 64, 68 (cross-stack item 6). VerisenseDevice.isSecondGenerationHardware already anticipates IDs above 68.
  • F8 Minor. ConsensysApps DialogFirmware.java:764 uses isShimmerGenGq(), now true for a node, so a GQ MSP430 image passes the UI compatibility check; #304's text claims the opposite. Only the Advance-API dock guard catches it later.
  • Nits. Test IDs API_00012 and API_00013 now collide with master's (different class names, so nothing breaks); new tests not in API_00005_Suite_ShimmerDriver; "1915" duplicates the VID_1915&PID_520F literal; two independent "NeuroLynQ-mode" definitions (product string vs hardware plus firmware 9) are never reconciled.
  • Tests. API_00012 restates enum logic with no negative substring case; API_00013 has no no-trailing-hyphen or VID case; API_00014 hard-codes the same five IDs as the implementation and does not test mFirmwareVersionCode or the seven Configuration lists.

Cross-stack issues (shared by all six reviews)

  1. Stale heads in the DEV-1061 stack. Advance-API #482's head lacks the last two commits of its own base (the Span crash fix and the channel rating that adds eventSpanManagerSpectrumAnalyzerScanFailed). ConsensysApps #493's head lacks its base's last commit. GitHub merges both cleanly, and the merged three-repo stack was compiled (main and test sources, all three repos), but the trees the author tested are not the trees that will land.
  2. Master has moved. Driver master is 34 commits past #308's branch point, Advance-API master 13 past #483's. Both merge cleanly into their master-targeted PRs and the merged trees build and pass. But #482 textually conflicts with Advance-API master in ShimmerSDLog.processSDLogHeader, where DEV-1123's pressure-ID warning and this PR's parseNeuroLynQPpgChannels land on the same lines. Resolve by keeping both. Also, Advance-API master now needs the driver's SdHeaderPressureSensorId, so the final landing needs driver master plus #306 together.
  3. DEV-1095 (SD timestamp anchor) now applies to node files via the parseTimestampShimmer3 gate #306 opens. It was verified on Shimmer3 only. Re-run ADV_API_00078 (golden node files) against a master-merged driver before merging.
  4. CI never ran on #306, #482 or #493. The workflows trigger only on PRs into master. When #482 does reach master, ADV_API_00081 will go red on ubuntu (see #482 B1).
  5. CI clone URLs in ConsensysApps and Shimmer-Advance-API gradle.yml still point at github.com/ShimmerEngineering/… and work only through GitHub's rename redirect. Advance-API master already fixed its own (DEV-1126); the #483 branch predates that fix.
  6. Hardware ID 61 to 68. The PR text and javadocs say a node is "hardware ID 61 to 68", but isShimmerGenVerisense lists only 61, 62, 63, 64 and 68. A node on 65 to 67 would be a plain GQ (SD access true, no PPG, no storage download). Either fix the text everywhere or the range.
  7. Windows only. The nRF52840 Span and the NeuroLynQ node are detected only in DeviceInfoWin. DeviceInfoLinux and DeviceInfoMac are untouched, although the javadoc claims "every platform's detection calls this" and the release workflow builds macOS installers.
  8. No JDK 11 here. Every build and test in this review ran on JDK 21 with source/target 11. One pre-existing Mockito test fails on 21 and was ignored.

Notes

All builds and tests in this review ran on JDK 21 with source/target 11; no JDK 11 was available. Nothing here was run on hardware. Full report with the verification table is held by the reviewer; findings are ordered most severe first. Verdict is given in the text; the approve/request-changes decision is left to the human reviewer.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants